<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->

<B><A HREF="PRINTF.html">PRINTF(3)</A></B>	       FreeBSD Library Functions Manual 	     <B><A HREF="PRINTF.html">PRINTF(3)</A></B>


</PRE>
<H2>NAME</H2><PRE>
     <B>printf</B>, <B>fprintf</B>, <B>sprintf</B>, <B>snprintf</B>, <B>asprintf</B>, <B>vprintf</B>, <B>vfprintf,</B>
     <B>vsprintf</B>, <B>vsnprintf</B>, <B>vasprintf</B> - formatted output conversion


</PRE>
<H2>SYNOPSIS</H2><PRE>
     <B>#include</B> <B>&lt;stdio.h&gt;</B>

     <I>int</I>
     <B>printf</B>(<I>const</I> <I>char</I> <I>*format</I>, <I>...</I>)

     <I>int</I>
     <B>fprintf</B>(<I>FILE</I> <I>*stream</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>...</I>)

     <I>int</I>
     <B>sprintf</B>(<I>char</I> <I>*str</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>...</I>)

     <I>int</I>
     <B>snprintf</B>(<I>char</I> <I>*str</I>, <I>size</I><B>_</B><I>t</I> <I>size</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>...</I>)

     <I>int</I>
     <B>asprintf</B>(<I>char</I> <I>**ret</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>...</I>)

     <B>#include</B> <B>&lt;stdarg.h&gt;</B>

     <I>int</I>
     <B>vprintf</B>(<I>const</I> <I>char</I> <I>*format</I>, <I>va</I><B>_</B><I>list</I> <I>ap</I>)

     <I>int</I>
     <B>vfprintf</B>(<I>FILE</I> <I>*stream</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>va</I><B>_</B><I>list</I> <I>ap</I>)

     <I>int</I>
     <B>vsprintf</B>(<I>char</I> <I>*str</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>va</I><B>_</B><I>list</I> <I>ap</I>)

     <I>int</I>
     <B>vsnprintf</B>(<I>char</I> <I>*str</I>, <I>size</I><B>_</B><I>t</I> <I>size</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>va</I><B>_</B><I>list</I> <I>ap</I>)

     <I>int</I>
     <B>vasprintf</B>(<I>char</I> <I>**ret</I>, <I>const</I> <I>char</I> <I>*format</I>, <I>va</I><B>_</B><I>list</I> <I>ap</I>)


</PRE>
<H2>DESCRIPTION</H2><PRE>
     The <B>printf</B>() family of functions produces output according to a <I>format</I> as
     described below.  <B>Printf</B>() and <B>vprintf</B>() write output to <I>stdout,</I> the
     standard output stream; <B>fprintf</B>() and <B>vfprintf</B>() write output to the giv-
     en output <I>stream</I>; <B>sprintf</B>(), <B>snprintf</B>(), <B>vsprintf</B>(), and <B>vsnprintf</B>()
     write to the character string <I>str</I>; and <B>asprintf</B>() and <B>vasprintf</B>() dynami-
     cally allocate a new string with <B><A HREF="malloc.html">malloc(3)</A></B> / <B><A HREF="malloc.html">realloc(3)</A></B>.

     These functions write the output under the control of a <I>format</I> string
     that specifies how subsequent arguments (or arguments accessed via the
     variable-length argument facilities of <B><A HREF="stdarg.html">stdarg(3)</A></B>)	are converted for out-
     put.

     These functions return the number of characters printed (not including
     the trailing `\0' used to end output to strings).

     <B>Asprintf</B>() and <B>vasprintf</B>() return a pointer to a buffer sufficiently
     large to hold the string in the <I>ret</I> argument; This pointer should be
     passed to <B><A HREF="malloc.html">free(3)</A></B> to release the allocated storage when it is no longer
     needed.  If sufficient space cannot be allocated, <B>asprintf</B>() and
     <B>vasprintf</B>() will return -1 and set <I>ret</I> to be a NULL pointer.

     <B>Snprintf</B>() and <B>vsnprintf</B>() will write at most <I>size</I>-1 of the characters
     printed into the output string (the <I>size</I>'th character then gets the ter-
     minating `\0'); if the return value is greater than or equal to the <I>size</I>
     argument, the string was too short and some of the printed characters
     were discarded.

     <B>Sprintf</B>() and <B>vsprintf</B>() effectively assume an infinite <I>size</I>.

     The format string is composed of zero or more directives: ordinary char-
     acters (not <B>%</B>), which are copied unchanged to the output stream; and con-
     version specifications, each of which results in fetching zero or more
     subsequent arguments.  Each conversion specification is introduced by the
     character <B>%</B>. The arguments must correspond properly (after type promo-
     tion) with the conversion specifier.  After the <B>%</B>, the following appear
     in sequence:

     <B>o</B>	 An optional field, consisting of a decimal digit string followed by a
	 <B>$</B>, specifying the next argument to access .  If this field is not
	 provided, the argument following the last argument accessed will be
	 used.	Arguments are numbered starting at <B>1</B>. If unaccessed arguments
	 in the format string are interspersed with ones that are accessed the
	 results will be indeterminate.

     <B>o</B>	 Zero or more of the following flags:

	 <B>-</B>   A <B>#</B> character specifying that the value should be converted to an
	     ``alternate form''.  For <B>c</B>, <B>d</B>, <B>i</B>, <B>n</B>, <B>p</B>, <B>s</B>, and <B>u</B>, conversions,
	     this option has no effect.  For <B>o</B> conversions, the precision of
	     the number is increased to force the first character of the out-
	     put string to a zero (except if a zero value is printed with an
	     explicit precision of zero).  For <B>x</B> and <B>X</B> conversions, a non-zero
	     result has the string `0x' (or `0X' for <B>X</B> conversions) prepended
	     to it.  For <B>e</B>, <B>E</B>, <B>f</B>, <B>g</B>, and <B>G</B>, conversions, the result will al-
	     ways contain a decimal point, even if no digits follow it (nor-
	     mally, a decimal point appears in the results of those conver-
	     sions only if a digit follows).  For <B>g</B> and <B>G</B> conversions, trail-
	     ing zeros are not removed from the result as they would otherwise
	     be.

	 <B>-</B>   A zero `<B>0</B>' character specifying zero padding.  For all conver-
	     sions except <B>n</B>, the converted value is padded on the left with
	     zeros rather than blanks.	If a precision is given with a numeric
	     conversion (<B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>i</B>, <B>x</B>, and <B>X</B>), the `<B>0</B>' flag is ignored.

	 <B>-</B>   A negative field width flag `<B>-</B>' indicates the converted value is
	     to be left adjusted on the field boundary.  Except for <B>n</B> conver-
	     sions, the converted value is padded on the right with blanks,
	     rather than on the left with blanks or zeros.  A `<B>-</B>' overrides a
	     `<B>0</B>' if both are given.

	 <B>-</B>   A space, specifying that a blank should be left before a positive
	     number produced by a signed conversion (<B>d</B>, <B>e</B>, <B>E</B>, <B>f</B>, <B>g</B>, <B>G</B>, or <B>i</B>).

	 <B>-</B>   A `<B>+</B>' character specifying that a sign always be placed before a
	     number produced by a signed conversion.  A `<B>+</B>' overrides a space
	     if both are used.

     <B>o</B>	 An optional decimal digit string specifying a minimum field width.
	 If the converted value has fewer characters than the field width, it
	 will be padded with spaces on the left (or right, if the left-adjust-
	 ment flag has been given) to fill out the field width.

     <B>o</B>	 An optional precision, in the form of a period `<B>.</B>' followed by an op-
	 tional digit string.  If the digit string is omitted, the precision
	 is taken as zero.  This gives the minimum number of digits to appear
	 for <B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>x</B>, and <B>X</B> conversions, the number of digits to appear
	 after the decimal-point for <B>e</B>, <B>E</B>, and <B>f</B> conversions, the maximum num-
	 ber of significant digits for <B>g</B> and <B>G</B> conversions, or the maximum
	 number of characters to be printed from a string for <B>s</B> conversions.

     <B>o</B>	 The optional character <B>h</B>, specifying that a following <B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>x</B>,
	 or <B>X</B> conversion corresponds to a <I>short</I> <I>int</I> or <I>unsigned</I> <I>short</I> <I>int</I> ar-
	 gument, or that a following <B>n</B> conversion corresponds to a pointer to
	 a <I>short</I> <I>int</I> argument.

     <B>o</B>	 The optional character <B>l</B> (ell) specifying that a following <B>d</B>, <B>i</B>, <B>o</B>,
	 <B>u</B>, <B>x</B>, or <B>X</B> conversion applies to a pointer to a <I>long</I> <I>int</I> or <I>unsigned</I>
	 <I>long</I> <I>int</I> argument, or that a following <B>n</B> conversion corresponds to a
	 pointer to a <I>long</I> <I>int</I> argument.

     <B>o</B>	 The optional character <B>q</B>, specifying that a following <B>d</B>, <B>i</B>, <B>o</B>, <B>u</B>, <B>x</B>,
	 or <B>X</B> conversion corresponds to a <I>quad</I> <I>int</I> or <I>unsigned</I> <I>quad</I> <I>int</I> argu-
	 ment, or that a following <B>n</B> conversion corresponds to a pointer to a
	 <I>quad</I> <I>int</I> argument.

     <B>o</B>	 The character <B>L</B> specifying that a following <B>e</B>, <B>E</B>, <B>f</B>, <B>g</B>, or <B>G</B> conver-
	 sion corresponds to a <I>long</I> <I>double</I> argument (but note that long double
	 values are not currently supported by the VAX and Tahoe compilers).

     <B>o</B>	 A character that specifies the type of conversion to be applied.

     A field width or precision, or both, may be indicated by an asterisk `*'
     or an asterisk followed by one or more decimal digits and a `$' instead
     of a digit string.  In this case, an <I>int</I> argument supplies the field
     width or precision.  A negative field width is treated as a left adjust-
     ment flag followed by a positive field width; a negative precision is
     treated as though it were missing.  If a single format directive mixes
     positional (nn$) and non-positional arguments, the results are undefined.

     The conversion specifiers and their meanings are:

     <B>diouxX</B>  The <I>int</I> (or appropriate variant) argument is converted to signed
	     decimal (<B>d</B> and <B>i</B>), unsigned octal (<B>o</B>), unsigned decimal (<B>u</B>), or
	     unsigned hexadecimal (<B>x</B> and <B>X</B>) notation.  The letters <B>abcdef</B> are
	     used for <B>x</B> conversions; the letters <B>ABCDEF</B> are used for <B>X</B> conver-
	     sions.  The precision, if any, gives the minimum number of digits
	     that must appear; if the converted value requires fewer digits,
	     it is padded on the left with zeros.

     <B>DOU</B>     The <I>long</I> <I>int</I> argument is converted to signed decimal, unsigned
	     octal, or unsigned decimal, as if the format had been <B>ld</B>, <B>lo</B>, or
	     <B>lu</B> respectively.  These conversion characters are deprecated, and
	     will eventually disappear.

     <B>eE</B>      The <I>double</I> argument is rounded and converted in the style
	     [-]d<B>.</B>ddd<B>e</B>+-dd where there is one digit before the decimal-point
	     character and the number of digits after it is equal to the pre-
	     cision; if the precision is missing, it is taken as 6; if the
	     precision is zero, no decimal-point character appears.  An <B>E</B> con-
	     version uses the letter <B>E</B> (rather than <B>e</B>) to introduce the expo-
	     nent.  The exponent always contains at least two digits; if the
	     value is zero, the exponent is 00.

     <B>f</B>	     The <I>double</I> argument is rounded and converted to decimal notation
	     in the style [-]ddd<B>.</B>ddd, where the number of digits after the
	     decimal-point character is equal to the precision specification.
	     If the precision is missing, it is taken as 6; if the precision
	     is explicitly zero, no decimal-point character appears.  If a
	     decimal point appears, at least one digit appears before it.

     <B>g</B>	     The <I>double</I> argument is converted in style <B>f</B> or <B>e</B> (or <B>E</B> for <B>G</B> con-
	     versions).  The precision specifies the number of significant
	     digits.  If the precision is missing, 6 digits are given; if the
	     precision is zero, it is treated as 1.  Style <B>e</B> is used if the
	     exponent from its conversion is less than -4 or greater than or
	     equal to the precision.  Trailing zeros are removed from the
	     fractional part of the result; a decimal point appears only if it
	     is followed by at least one digit.

     <B>c</B>	     The <I>int</I> argument is converted to an <I>unsigned</I> <I>char</I>, and the re-
	     sulting character is written.

     <B>s</B>	     The ``<I>char</I> <I>*</I>'' argument is expected to be a pointer to an array
	     of character type (pointer to a string).  Characters from the ar-
	     ray are written up to (but not including) a terminating NUL char-
	     acter; if a precision is specified, no more than the number spec-
	     ified are written.  If a precision is given, no null character
	     need be present; if the precision is not specified, or is greater
	     than the size of the array, the array must contain a terminating
	     NUL character.

     <B>p</B>	     The ``<I>void</I> <I>*</I>'' pointer argument is printed in hexadecimal (as if
	     by `%#x' or `%#lx').

     <B>n</B>	     The number of characters written so far is stored into the inte-
	     ger indicated by the ``<I>int</I> <I>*</I>'' (or variant) pointer argument.  No
	     argument is converted.

     <B>%</B>	     A `%' is written. No argument is converted. The complete conver-
	     sion specification is `%%'.

     In no case does a non-existent or small field width cause truncation of a
     field; if the result of a conversion is wider than the field width, the
     field is expanded to contain the conversion result.


</PRE>
<H2>EXAMPLES</H2><PRE>
     To print a date and time in the form `Sunday, July 3, 10:02', where
     <I>weekday</I> and <I>month</I> are pointers to strings:

	   #include &lt;stdio.h&gt;
	   fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
		   weekday, month, day, hour, min);

     To print pi to five decimal places:

	   #include &lt;math.h&gt;
	   #include &lt;stdio.h&gt;
	   fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

     To allocate a 128 byte string and print into it:

	   #include &lt;stdio.h&gt;
	   #include &lt;stdlib.h&gt;
	   #include &lt;stdarg.h&gt;
	   char *newfmt(const char *fmt, ...)
	   {
			   char *p;
			   va_list ap;
			   if ((p = malloc(128)) == NULL)
				   return (NULL);
			   va_start(ap, fmt);
			   (void) vsnprintf(p, 128, fmt, ap);
			   va_end(ap);
			   return (p);
	   }


</PRE>
<H2>SEE ALSO</H2><PRE>
     <B><A HREF="printf.html">printf(1)</A></B>,  <B><A HREF="scanf.html">scanf(3)</A></B>


</PRE>
<H2>STANDARDS</H2><PRE>
     The <B>fprintf</B>(), <B>printf</B>(), <B>sprintf</B>(), <B>vprintf</B>(), <B>vfprintf</B>(), and <B>vsprintf</B>()
     functions conform to ISO 9899: 1990 (``ISO C'').


</PRE>
<H2>HISTORY</H2><PRE>
     The functions <B>asprintf</B>() and <B>vasprintf</B>() first appeared in the GNU C li-
     brary.  These were implemented by Peter Wemm &lt;peter@FreeBSD.org&gt; in
     FreeBSD 2.2, but were later replaced with a different implementation from
     Todd C. Miller &lt;Todd.Miller@courtesan.com&gt; for OpenBSD 2.3.


</PRE>
<H2>BUGS</H2><PRE>
     The conversion formats <B>%D</B>, <B>%O</B>, and <B>%U</B> are not standard and are provided
     only for backward compatibility.  The effect of padding the <B>%p</B> format
     with zeros (either by the `<B>0</B>' flag or by specifying a precision), and the
     benign effect (i.e., none) of the `<B>#</B>' flag on <B>%n</B> and <B>%p</B> conversions, as
     well as other nonsensical combinations such as <B>%Ld</B>, are not standard;
     such combinations should be avoided.

     Because <B>sprintf</B>() and <B>vsprintf</B>() assume an infinitely long string,
     callers must be careful not to overflow the actual space; this is often
     hard to assure.  For safety, programmers should use the <B>snprintf</B>() inter-
     face instead.  Unfortunately, this interface is not portable.

BSD				 June 4, 1993				     5
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
